The purpose of the Serialized Form specification is to ensure that a serialized object can successfully be passed between different implementations of the Java Platform.
This is Oracle's criteria for determining if a class should be included in the serialized form specification:
Serializable
(directly or indirectly through implements
or
extends
) then its serial form must be included
in the spec. An example is the public class
java.applet.Applet
(which indirectly extends
Component
which implements Serializable
).Serializable
,
and a user of a public class can, via a factory method,
access that object, and if the spec (doc comment) explicitly
guarantees that the object is serializable, then the serial form
must be included. An example is the private class
java.util.Arrays.ArrayList
.In both cases, rare exceptions can be made where the class in question was never intended to be serialized across implementations or releases. (The excluded Swing classes fall into this category. Swing uses a different mechanism to provide the needed functionality.)
To satisfy this criteria, the design engineer of each class needs to verify whether that class is actually part of the published serialized form of a public or protected API class, rather than just a class used in the implementation that also happens to be serializable.
Note - Interfaces do not have serialized forms, and so would not appear in the Serialized Form specification.
By default, version 1.3 of Javadoc includes public and protected classes that implement Serializable, and excludes private and package-private classes that implement Serializable. Version 1.3 of Javadoc has no mechanism for excluding the former from or including the latter in the Serialized Form spec, as may be needed in satisfying the above criteria.
We have instituted a mechanism in Javadoc 1.4 for marking serializable classes for inclusion or exclusion in the spec. (We used it for generating the 1.3 serialized form spec, but the mechanism was implemented too late to be included in Javadoc 1.3.) It does the following:
Serializable
, unless they or their packages are
marked with @serial exclude
Serializable
, unless they or their packages are marked
with @serial include
The Javdaoc 1.4 reference page also describes this.